Responds to cursor movements in a control while the mouse button is down.

ControlPartCode TrackControl (
    ControlRef theControl, 
    Point startPoint, 
    ControlActionUPP actionProc
);

theControl

A handle to the control in which a mouse-down event occurred.

startPoint

A point, specified in coordinates local to the window, where the mouse-down event occurred.

actionProc

A pointer to an action function defining what action your application takes while the user holds down the mouse button. The value of the actionProc parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL). See ControlActionProcPtr for information about an action function to specify in this parameter.

function result

If the user releases the mouse button while the cursor is inside a control part, TrackControl returns a value of type ControlPartCode identifying the control part in which the mouse-up event occurs; see “Meta Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. TrackControl returns 0 if the user releases the mouse button while the cursor is outside the control part. If the user releases the mouse button when the cursor is in an indicator such as a scroll box, TrackControl calls the control’s control definition function to reposition the indicator.

DISCUSSION

When the Appearance Manager is available, you should typically call HandleControlClick instead of TrackControl to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike the TrackControl function, HandleControlClick also accepts modifier key information so that the control may take into account the current modifier key state if the control is set up to handle its own tracking.

If the Appearance Manager is not available, you can use the TrackControl function to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. The visual feedback given by TrackControl depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, TrackControl highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, TrackControl responds by dragging a dotted outline of the indicator.

While the user holds down the mouse button with the cursor in one of the standard controls, TrackControl performs the following actions, depending on the value you pass in the parameter actionProc. (For other controls, what you pass in this parameter depends on how you define the control.)

• If you pass NULL in the actionProc parameter, TrackControl uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
• If you pass a pointer to an action function in the actionProc parameter, you must provide the function, and it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar.
• If you pass Pointer(–1) in the actionProc parameter, TrackControl looks in the contrlAction field of the control structure for a pointer to the control’s action function. This is appropriate when you are tracking the cursor in a pop-up menu. (You can use the GetControlAction function to determine the value of this field, and you can use the SetControlAction function to change this value.) If the contrlAction field of the control structure contains a function pointer, TrackControl uses the action function it points to; if the field of the control structure also contains the value Pointer(–1), TrackControl calls the control’s control definition function to perform the necessary action; you may wish to do this if you define your own control definition function for a custom control. If the field of the control structure contains the value NULL, TrackControl performs no action.

Note that when you need to handle events in alert and dialog boxes, Dialog Manager functions automatically call FindControl and TrackControl.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)